package com.srmt.document.api;

import com.srmt.document.model.DocumentInfo;
import com.srmt.document.model.PermissionSetting;
import com.srmt.document.exception.DocumentException;
import com.srmt.document.exception.DocumentNotFoundException;
import com.srmt.document.exception.PermissionDeniedException;

/**
 * 文档管理接口
 * 负责文档的创建、权限管理、基础操作
 * 
 * @author YourCompany
 * @since 1.0.0
 */
public interface DocumentManager {
    
    /**
     * 根据模板创建文档
     * 
     * @param templateId 模板ID，如果为null则创建空白文档
     * @param title 文档标题
     * @param folderToken 目标文件夹token，为null时使用默认文件夹
     * @return 创建的文档ID
     * @throws DocumentException 文档创建失败时抛出
     */
    String createFromTemplate(String templateId, String title, String folderToken) throws DocumentException;
    
    /**
     * 创建空白文档
     * 
     * @param title 文档标题
     * @param folderToken 目标文件夹token
     * @return 创建的文档ID
     * @throws DocumentException 文档创建失败时抛出
     */
    default String createBlankDocument(String title, String folderToken) throws DocumentException {
        return createFromTemplate(null, title, folderToken);
    }
    
    /**
     * 设置文档权限
     * 
     * @param docId 文档ID
     * @param permission 权限设置
     * @throws PermissionDeniedException 没有权限设置时抛出
     * @throws DocumentNotFoundException 文档不存在时抛出
     */
    void setPermissions(String docId, PermissionSetting permission) 
            throws PermissionDeniedException, DocumentNotFoundException;
    
    /**
     * 调整用户权限
     * 
     * @param docId 文档ID
     * @param userId 用户ID
     * @param permission 权限类型（view, edit, comment, full_access）
     * @throws PermissionDeniedException 没有权限设置时抛出
     * @throws DocumentNotFoundException 文档不存在时抛出
     */
    void adjustPermissions(String docId, String userId, String permission) 
            throws PermissionDeniedException, DocumentNotFoundException;
    
    /**
     * 移除用户权限
     * 
     * @param docId 文档ID
     * @param userId 用户ID
     * @throws PermissionDeniedException 没有权限设置时抛出
     * @throws DocumentNotFoundException 文档不存在时抛出
     */
    void removePermission(String docId, String userId)
            throws PermissionDeniedException, DocumentNotFoundException;
    
    /**
     * 获取文档基本信息
     * 
     * @param docId 文档ID
     * @return 文档基本信息
     * @throws DocumentNotFoundException 文档不存在时抛出
     */
    DocumentInfo getDocumentInfo(String docId) throws DocumentNotFoundException;
    
    /**
     * 删除文档
     * 
     * @param docId 文档ID
     * @throws DocumentException 删除失败时抛出
     * @throws DocumentNotFoundException 文档不存在时抛出
     */
    void deleteDocument(String docId) throws DocumentException, DocumentNotFoundException;
    
    /**
     * 复制文档
     * 
     * @param sourceDocId 源文档ID
     * @param newTitle 新文档标题
     * @param folderToken 目标文件夹token，为null时使用默认文件夹
     * @return 新文档的ID
     * @throws DocumentException 复制失败时抛出
     * @throws DocumentNotFoundException 源文档不存在时抛出
     */
    String copyDocument(String sourceDocId, String newTitle, String folderToken) 
            throws DocumentException, DocumentNotFoundException;
    
    /**
     * 获取文档的访问URL
     * 
     * @param docId 文档ID
     * @return 文档的访问URL
     * @throws DocumentNotFoundException 文档不存在时抛出
     */
    String getDocumentUrl(String docId) throws DocumentNotFoundException;
    
    /**
     * 刷新文档权限 - 清空所有现有权限后重新设置
     * 
     * @param docId 文档ID
     * @param permission 新的权限设置
     * @throws PermissionDeniedException 没有权限设置时抛出
     * @throws DocumentNotFoundException 文档不存在时抛出
     */
    void refreshPermissions(String docId, PermissionSetting permission) 
            throws PermissionDeniedException, DocumentNotFoundException;
}